<dependency> <groupId>org.picketbox</groupId> <artifactId>picketbox-http</artifactId> <version>${picketbox.version}</version> </dependency>
This tutorial will show you how to get started using PicketBox in a simple web application.
This is the fastest way to get started. It is a very nice way to understand some basic concepts and how get things to work.
<dependency> <groupId>org.picketbox</groupId> <artifactId>picketbox-http</artifactId> <version>${picketbox.version}</version> </dependency>
PicketBox comes shipped with an important servlet filter called org.picketbox.http.filters.DelegatingSecurityFilter.
To enable PicketBox HTTP Security in your application the first thing you should do is define this filter in your web.xml. See the example bellow:
<!-- Configures FORM authentication scheme --> <context-param> <param-name>org.picketbox.authentication</param-name> <param-value>FORM</param-value> </context-param> <!-- Custom ConfigurationBuilderProvider to provide a custom configuration using the Configuration API. --> <context-param> <param-name>org.picketbox.configuration.provider</param-name> <param-value>org.picketbox.quickstarts.configuration.CustomConfigurationPovider</param-value> </context-param> <!-- Configures the PicketBox Security Filter --> <filter> <filter-name>PicketBox Delegating Filter</filter-name> <filter-class>org.picketbox.http.filters.DelegatingSecurityFilter</filter-class> </filter> <!-- Configures all resources as protected by the PicketBox Security Filter --> <filter-mapping> <filter-name>PicketBox Delegating Filter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
org.picketbox.authentication: This parameter defines which authentication scheme should be used. Possible values are FORM, BASIC, DIGEST and CLIENT_CERT. In our example we are using HTTP Form Authentication.
org.picketbox.configuration.provider: This parameter configures a org.picketbox.http.config.ConfigurationBuilderProvider implementation. The specified class will be used to produce the PicketBox configuration.
The code bellow shows how the org.picketbox.quickstarts.configuration.CustomConfigurationPovider class looks like:
public class CustomConfigurationPovider implements ConfigurationBuilderProvider { /* * (non-Javadoc) * * @see org.picketbox.http.config.ConfigurationBuilderProvider#getBuilder(javax.servlet.ServletContext) */ @Override public HTTPConfigurationBuilder getBuilder(ServletContext servletcontext) { HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder(); // protected resources configuration configurationBuilder.protectedResource() // unprotected resource. Usually this will be your application's static resources like CSS, JS, etc. .resource("/resources/*", ProtectedResourceConstraint.NOT_PROTECTED) // the login page is marked as not protected. .resource("/login.jsp", ProtectedResourceConstraint.NOT_PROTECTED) // the error page is marked as not protected. .resource("/error.jsp", ProtectedResourceConstraint.NOT_PROTECTED) // protected all resources. They will be available only for users with a role named 'guest'. .resource("/*", "guest"); return configurationBuilder; } }
You should always provide your own ConfigurationBuilderProvider implementation to configure the PicketBox behaviour. In the previous example we just configured the protected resource but there are some other configurations that you might find useful like:
Choose between the different Identity Store implementations (eg.: JPA and LDAP)
Session Management
Authorization using a built-in or specific Authorization Manager (eg.: drools-based authorization)
Event Handling to be notified about security events when an authentication is done or fail.
Auditing
For more information about the PicketBox configuration, check the Configuration API documentation.